home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 2002 November / SGI Freeware 2002 November - Disc 2.iso / dist / fw_gtk+.idb / usr / freeware / doc / gtk / gtk-config.txt.z / gtk-config.txt
Text File  |  2001-10-09  |  7KB  |  237 lines
  1. CONFIGURING PACKAGES TO WORK WITH GTK
  2. -------------------------------------
  3.  
  4. Compiling a program succesfully against the GTK, GDK, and GLIB
  5. libraries can require a large number of command line options
  6. to your compiler and linker that are hard to guess correctly.
  7. The additional libraries required may, for example, depend on the
  8. manner which GTK was configured
  9.  
  10. Several tools are included in this package to make process
  11. easier.
  12.  
  13. First, there is the shell script 'gtk-config' (installed in
  14. $exec_prefix/bin):
  15.  
  16. Invoking gtk-config
  17. -------------------
  18.  
  19. gtk-config takes the following flags:
  20.  
  21.   --version
  22.      Prints out the version of GTK installed
  23.  
  24.   --cflags
  25.      Prints '-I' flags pointing to the installed header files.
  26.  
  27.   --libs
  28.      Prints out the linker flags necessary to link a program against GTK
  29.    
  30.   --prefix[=PREFIX]
  31.      If PREFIX is specified, overrides the configured value of $prefix.
  32.      (And of exec-prefix, unless --exec-prefix is also specified)
  33.      Otherwise, prints out the configured value of $prefix
  34.  
  35.   --exec-prefix[=PREFIX]
  36.      If PREFIX is specified, overrides the configured value of $exec_prefix.
  37.      Otherwise, prints out the configured value of $exec_prefix
  38.  
  39. You may also add to the command line a list of additional
  40. libraries that gtk-config should supply the CFLAGS and LIBS
  41. for. The only currently supported library is 'gthread'.
  42.  
  43. As an example of this latter usage, you can get the
  44. appropriate cflags for a threaded program with:
  45.  
  46.  gtk-config --cflags gthread
  47.  
  48.  
  49. Example of using gtk-config
  50. ---------------------------
  51.  
  52. Typically, gtk-config will be used within a configure script,
  53. as described below. It, however, can also be used directly
  54. from the command line to compile a simple program. For example:
  55.  
  56.   cc -o simple `gtk-config --cflags` simple.c `gtk-config --libs`
  57.  
  58. This command line might expand to (for example):
  59.  
  60.   cc -o simple -I/usr/local/lib/glib/include -I/usr/local/include \
  61.     -I/usr/X11R6/include simple.c -L/usr/local/lib -L/usr/X11R6/lib \
  62.     -lgtk -lgdk -lglib -lXi -lXext -lX11 -lm
  63.  
  64. Not only is the form using gtk-config easier to type, it will
  65. work on any system, no matter how GTK was configured.
  66.  
  67.  
  68. AM_PATH_GTK
  69. -----------
  70.  
  71. For packages configured using GNU automake, GTK also provides
  72. a macro to automate the process of running GTK.
  73.  
  74.  AM_PATH_GTK([MINIMUM-VERSION, [ACTION-IF-FOUND [, ACTION-IF-NOT-FOUND]]])
  75.  
  76. This macro:
  77.  
  78.  * Determines the location of GTK using gtk-config, which is either
  79.    found in the user's path, or from the environment variable
  80.    GTK_CONFIG
  81.  
  82.  * Tests the installed libraries to make sure that there version
  83.    is later than MINIMUM-VERSION. (A default version will be used
  84.    if not specified)
  85.  
  86.  * If the required version was found, sets the GTK_CFLAGS variable to
  87.    the output of `gtk-config --cflags` and the GTK_LIBS variable to
  88.    the output of `gtk-config --libs`, and calls AC_SUBST() for these
  89.    variables so they can be used in generated makefiles, and then
  90.    executes ACTION-IF-FOUND.
  91.  
  92.  * If the required version was not found, sets GTK_CFLAGS and GTK_LIBS
  93.    to empty strings, and executes ACTION-IF-NOT-FOUND.
  94.  
  95. This macro is in file 'gtk.m4' which is installed in $datadir/aclocal.
  96. Note that if automake was installed with a different --prefix than
  97. GTK, you will either have to manually move gtk.m4 to automake's
  98. $datadir/aclocal, or give aclocal the -I option when running it.
  99.  
  100.  
  101. Configuring a package that uses AM_PATH_GTK
  102. -------------------------------------------
  103.  
  104. Simply make sure that gtk-config is in your path, and run
  105. the configure script.
  106.  
  107. Notes:
  108.  
  109. * The directory where the GTK libraries are installed needs
  110.   to be found by your system's dynamic linker.
  111.   
  112.   This is generally done by
  113.  
  114.     editing /etc/ld.so.conf and running ldconfig
  115.  
  116.   Or by:
  117.    
  118.     setting the environment variable LD_LIBRARY_PATH, 
  119.  
  120.   or, as a last resort, 
  121.  
  122.     Giving a -R or -rpath flag (depending on your linker) when
  123.     running configure, for instance:
  124.  
  125.       LDFLAGS=-R/usr/home/owen/lib ./configure
  126.  
  127. * You can also specify a gtk-config not in your path by
  128.   setting the GTK_CONFIG environment variable to the
  129.   name of the executable
  130.  
  131. * If you move the GTK package from its installed location,
  132.   you will need either need to modify gtk-config script
  133.   manually to point to the new location or rebuild GTK.
  134.  
  135. Advanced note:
  136.  
  137. * configure flags
  138.   
  139.   --with-gtk-prefix=PREFIX
  140.   --with-gtk-exec-prefix=PREFIX 
  141.  
  142.   are provided to override the prefix and exec-prefix that were stored
  143.   in the gtk-config shell script by GTK's configure. You are generally
  144.   better off configuring GTK with the right path to begin with.
  145.  
  146. Example of a package using AM_PATH_GTK
  147. --------------------------------------
  148.  
  149. The following shows how to build a simple package using automake
  150. and the AM_PATH_GTK macro. The program used here is the testinput.c
  151.  
  152. You should first read the introductory portions of the automake
  153. Manual, if you are not already familiar with it.
  154.  
  155. Two files are needed, 'configure.in', which is used to build the
  156. configure script:
  157.  
  158. ==configure.in===
  159. dnl Process this file with autoconf to produce a configure script.
  160. AC_INIT(testinput.c)
  161.  
  162. AM_INIT_AUTOMAKE(testinput.c, 1.0.0)
  163.  
  164. AC_PROG_CC
  165. AM_PROG_CC_STDC
  166. AC_PROG_INSTALL
  167.  
  168. AM_PATH_GTK(0.99.5,
  169.           [LIBS="$LIBS $GTK_LIBS"
  170.            CFLAGS="$CFLAGS $GTK_CFLAGS"],
  171.        AC_MSG_ERROR(Cannot find GTK: Is gtk-config in path?))
  172.  
  173. AC_OUTPUT(Makefile)
  174. =================
  175.  
  176. The only command in this which is not standard for automake
  177. is the AM_PATH_GTK() macro.
  178.  
  179. That command does the following:
  180.  
  181.  If a GTK version greater than 0.99.5 is found, adds $GTK_LIBS to 
  182.  $LIBS and $GTK_CFLAGS to $CFLAGS. Otherwise, dies with the error
  183.  message "Cannot find GTK: Is gtk-config in path?"
  184.  
  185. And the 'Makefile.am', which will be used to build the Makefile.
  186.  
  187. == Makefile.am ==
  188. bin_PROGRAMS = testinput
  189. testinput_SOURCES = testinput.c
  190. =================
  191.  
  192. This Makefile.am, says that we are building a single executable,
  193. from a single sourcefile 'testinput.c'. Since every program
  194. we are building uses GTK we simply added the GTK options
  195. to $LIBS and $CFLAGS, but in other circumstances, we might
  196. want to specify them on a per-program basis: for instance by
  197. adding the lines:
  198.  
  199.   testinput_LDADD = $(GTK_LIBS)
  200.   INCLUDES = $(GTK_CFLAGS)
  201.  
  202. to the Makefile.am.
  203.  
  204. To try this example out, create a new directory, add the two
  205. files above two it, and copy the testinput.c file from 
  206. the gtk/ subdirectory to the new directory. Edit the line:
  207.  
  208.   #include "gtk.h"
  209.  
  210. in testgtk.c, to read:
  211.  
  212.   #include <gtk/gtk.h>
  213.  
  214.  
  215. Now execute the following commands:
  216.  
  217.   automake --add-missing
  218.   aclocal
  219.   autoconf
  220.   
  221. You now have a package that can be built in the normal fashion
  222.  
  223.   ./configure
  224.   make
  225.   make install
  226.  
  227.  
  228. Notes:
  229.  
  230. * If you are converting a package that used a pre-1.0 version of
  231.   GTK, you should remove the autoconf tests for X. The results
  232.   of these tests are included in gtk-config and will be added
  233.   to GTK_LIBS and GTK_CFLAGS by the AM_PATH_GTK macro.
  234.  
  235.                                         Owen Taylor
  236.                                         14 Mar 1997
  237.